home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2001 / MacHack 2001.toast / pc / The Hacks / pseudoDoc / ExampleHeaders / Media / IOMedia.h
Encoding:
C/C++ Source or Header  |  2001-06-23  |  17.8 KB  |  539 lines
  1. /*
  2.  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
  3.  *
  4.  * @APPLE_LICENSE_HEADER_START@
  5.  * 
  6.  * The contents of this file constitute Original Code as defined in and
  7.  * are subject to the Apple Public Source License Version 1.1 (the
  8.  * "License").  You may not use this file except in compliance with the
  9.  * License.  Please obtain a copy of the License at
  10.  * http://www.apple.com/publicsource and read it before using this file.
  11.  * 
  12.  * This Original Code and all software distributed under the License are
  13.  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14.  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15.  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16.  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17.  * License for the specific language governing rights and limitations
  18.  * under the License.
  19.  * 
  20.  * @APPLE_LICENSE_HEADER_END@
  21.  */
  22.  
  23. /*!
  24.  * @header IOMedia
  25.  * @abstract
  26.  * This header contains the IOMedia class definition.
  27.  */
  28.  
  29. #ifndef _IOMEDIA_H
  30. #define _IOMEDIA_H
  31.  
  32. /*!
  33.  * @defined kIOMediaClass
  34.  * @abstract
  35.  * kIOMediaClass is the name of the IOMedia class.
  36.  * @discussion
  37.  * kIOMediaClass is the name of the IOMedia class.
  38.  */
  39.  
  40. #define kIOMediaClass "IOMedia"
  41.  
  42. /*!
  43.  * @defined kIOMediaContent
  44.  * @abstract
  45.  * kIOMediaContent is a property of IOMedia objects.  It has an OSString value.
  46.  * @discussion
  47.  * The kIOMediaContent property contains a description of the media's contents.
  48.  * The description is the same as the hint at the time of the object's creation,
  49.  * but it is possible that the description be overrided by a client (which has
  50.  * probed the media and identified the content correctly) of the media object.
  51.  * It is more accurate than the hint for this reason.  The string is formed in
  52.  * the likeness of Apple's "Apple_HFS" strings.
  53.  */
  54.  
  55. #define kIOMediaContent "Content"
  56.  
  57. /*!
  58.  * @defined kIOMediaContentHint
  59.  * @abstract
  60.  * kIOMediaContentHint is a property of IOMedia objects.  It has an OSString
  61.  * value.
  62.  * @discussion
  63.  * The kIOMediaContentHint property contains a hint of the media's contents.
  64.  * The hint is set at the time of the object's creation, should the creator have
  65.  * a clue as to what it may contain.  The hint string does not change for the
  66.  * lifetime of the object and is formed in the likeness of Apple's "Apple_HFS"
  67.  * strings.
  68.  */
  69.  
  70. #define kIOMediaContentHint "Content Hint"
  71.  
  72. /*!
  73.  * @defined kIOMediaEjectable
  74.  * @abstract
  75.  * kIOMediaEjectable is a property of IOMedia objects.  It has an OSBoolean
  76.  * value.
  77.  * @discussion
  78.  * The kIOMediaEjectable property describes whether the media is ejectable.
  79.  */
  80.  
  81. #define kIOMediaEjectable "Ejectable"
  82.  
  83. /*!
  84.  * @defined kIOMediaLeaf
  85.  * @abstract
  86.  * kIOMediaLeaf is a property of IOMedia objects.  It has an OSBoolean value.
  87.  * @discussion
  88.  * The kIOMediaLeaf property describes whether the media is a leaf, that is, it
  89.  * is the deepest media object in this branch of the I/O Kit registry.
  90.  */
  91.  
  92. #define kIOMediaLeaf "Leaf"
  93.  
  94. /*!
  95.  * @defined kIOMediaPreferredBlockSize
  96.  * @abstract
  97.  * kIOMediaPreferredBlockSize is a property of IOMedia objects.  It has an
  98.  * OSNumber value.
  99.  * @discussion
  100.  * The kIOMediaPreferredBlockSize property describes the media's natural block
  101.  * size in bytes.  This information is useful to clients that want to optimize
  102.  * access to the media.
  103.  */
  104.  
  105. #define kIOMediaPreferredBlockSize "Preferred Block Size"
  106.  
  107. /*!
  108.  * @defined kIOMediaSize
  109.  * @abstract
  110.  * kIOMediaSize is a property of IOMedia objects.  It has an OSNumber value.
  111.  * @discussion
  112.  * The kIOMediaSize property describes the total length of the media in bytes.
  113.  */
  114.  
  115. #define kIOMediaSize "Size"
  116.  
  117. /*!
  118.  * @defined kIOMediaWhole
  119.  * @abstract
  120.  * kIOMediaWhole is a property of IOMedia objects.  It has an OSBoolean value.
  121.  * @discussion
  122.  * The kIOMediaWhole property describes whether the media is whole, that is, it
  123.  * represents the whole disk (the physical disk, or a virtual replica thereof).
  124.  */
  125.  
  126. #define kIOMediaWhole "Whole"
  127.  
  128. /*!
  129.  * @defined kIOMediaWritable
  130.  * @abstract
  131.  * kIOMediaWritable is a property of IOMedia objects.  It has an OSBoolean
  132.  * value.
  133.  * @discussion
  134.  * The kIOMediaWritable property describes whether the media is writable.
  135.  */
  136.  
  137. #define kIOMediaWritable "Writable"
  138.  
  139. /*!
  140.  * @defined kIOMediaContentMask
  141.  * @abstract
  142.  * kIOMediaContentMask is a property of IOMedia clients.  It has an OSString
  143.  * value.
  144.  * @discussion
  145.  * The kIOMediaContentMask property must exist in all IOMedia clients that drive
  146.  * new content (that is, produce new media objects).  When the client matches on
  147.  * the provider media, the value of the client's kIOMediaContentMask property is
  148.  * used to replace the provider's kIOMediaContent property.
  149.  */
  150.  
  151. #define kIOMediaContentMask "Content Mask"
  152.  
  153. /*
  154.  * Kernel
  155.  */
  156.  
  157. #if defined(KERNEL) && defined(__cplusplus)
  158.  
  159. #include <IOKit/storage/IOStorage.h>
  160.  
  161. /*!
  162.  * @class IOMedia
  163.  * @abstract
  164.  * The IOMedia class is a random-access disk device abstraction.
  165.  * @discussion
  166.  * The IOMedia class is a random-access disk device abstraction.   It provides a
  167.  * consistent interface for both real and virtual disk devices, for subdivisions
  168.  * of disks such as partitions, for supersets of disks such as RAID volumes, and
  169.  * so on.   It extends the IOStorage class by implementing the appropriate open,
  170.  * close, read, write, and matching semantics for media objects.  The properties
  171.  * it has reflect the properties of real disk devices,  such as ejectability and
  172.  * writability.
  173.  *
  174.  * The read and write interfaces support byte-level access to the storage space,
  175.  * with the appropriate deblocking handled by IODrive, however, a typical client
  176.  * will want to obtain the natural block size in order to optimize access to the
  177.  * real disk device.  A read or write is accepted so long as the client's access
  178.  * is valid, the media is formatted and the transfer is within the bounds of the
  179.  * media.  An optional non-zero base (offset) is then applied before the read or
  180.  * write is passed to provider object.
  181.  *
  182.  * An open is accepted so long as no more than one writer is active at any time.
  183.  */
  184.  
  185. class IOMedia : public IOStorage
  186. {
  187.     OSDeclareDefaultStructors(IOMedia)
  188.  
  189. protected:
  190.     bool            _isEjectable;
  191.     bool            _isWhole;
  192.     bool            _isWritable;
  193.  
  194.     UInt64          _mediaBase;  /* (relative to the storage object below us) */
  195.     UInt64          _mediaSize;
  196.  
  197.     IOStorageAccess _openLevel;
  198.     OSSet *         _openReaders;
  199.     IOService *     _openReaderWriter;
  200.  
  201.     UInt64          _preferredBlockSize;
  202.  
  203.     /*
  204.      * Free all of this object's outstanding resources.
  205.      */
  206.  
  207.     virtual void free();
  208.  
  209.     /*!
  210.      * @function handleOpen
  211.      * @discussion
  212.      * The handleOpen method grants or denies permission to access this object
  213.      * to an interested client.  The argument is an IOStorageAccess value that
  214.      * specifies the level of access desired -- reader or reader-writer.
  215.      *
  216.      * This method can be invoked to upgrade or downgrade the access level for
  217.      * an existing client as well.  The previous access level will prevail for
  218.      * upgrades that fail, of course.   A downgrade should never fail.  If the
  219.      * new access level should be the same as the old for a given client, this
  220.      * method will do nothing and return success.  In all cases, one, singular
  221.      * close-per-client is expected for all opens-per-client received.
  222.      *
  223.      * This implementation replaces the IOService definition of handleOpen().
  224.      * @param client
  225.      * Client requesting the open.
  226.      * @param options
  227.      * Options for the open.  Set to zero.
  228.      * @param access
  229.      * Access level for the open.  Set to kAccessReader or kAccessReaderWriter.
  230.      * @result
  231.      * Returns true if the open was successful, false otherwise.
  232.      */
  233.  
  234.     virtual bool handleOpen(IOService *  client,
  235.                             IOOptionBits options,
  236.                             void *       access);
  237.  
  238.     /*!
  239.      * @function handleIsOpen
  240.      * @discussion
  241.      * The handleIsOpen method determines whether the specified client, or any
  242.      * client if none is specificed, presently has an open on this object.
  243.      *
  244.      * This implementation replaces the IOService definition of handleIsOpen().
  245.      * @param client
  246.      * Client to check the open state of.  Set to zero to check the open state
  247.      * of all clients.
  248.      * @result
  249.      * Returns true if the client was (or clients were) open, false otherwise.
  250.      */
  251.  
  252.     virtual bool handleIsOpen(const IOService * client) const;
  253.  
  254.     /*!
  255.      * @function handleClose
  256.      * @discussion
  257.      * The handleClose method closes the client's access to this object.
  258.      *
  259.      * This implementation replaces the IOService definition of handleClose().
  260.      * @param client
  261.      * Client requesting the close.
  262.      * @param options
  263.      * Options for the close.  Set to zero.
  264.      */
  265.  
  266.     virtual void handleClose(IOService * client, IOOptionBits options);
  267.  
  268. public:
  269.  
  270. ///m:2333367:workaround:commented:start
  271. //  IOStorage::open;
  272. //  IOStorage::close;
  273. //  IOStorage::read;
  274. //  IOStorage::write;
  275. ///m:2333367:workaround:commented:stop
  276.  
  277. ///m:2333367:workaround:added:start
  278.     inline bool open(IOService *     client,
  279.                      IOOptionBits    options,
  280.                      IOStorageAccess access)
  281.     { return IOStorage::open(client, options, access); }
  282.  
  283.     virtual IOReturn read(IOService *          client,
  284.                           UInt64               byteStart,
  285.                           IOMemoryDescriptor * buffer,
  286.                           UInt64 *             actualByteCount = 0)
  287.     { return IOStorage::read(client, byteStart, buffer, actualByteCount); }
  288.  
  289.     virtual IOReturn write(IOService *          client,
  290.                            UInt64               byteStart,
  291.                            IOMemoryDescriptor * buffer,
  292.                            UInt64 *             actualByteCount = 0)
  293.     { return IOStorage::write(client, byteStart, buffer, actualByteCount); }
  294. ///m:2333367:workaround:added:stop
  295.  
  296.     /*!
  297.      * @function init
  298.      * @discussion
  299.      * Initialize this object's minimal state.
  300.      * @param base
  301.      * Media offset, in bytes.
  302.      * @param size
  303.      * Media size, in bytes.
  304.      * @param preferredBlockSize
  305.      * Natural block size, in bytes.
  306.      * @param isEjectable
  307.      * Indicates whether the media is ejectable.
  308.      * @param isWhole
  309.      * Indicated whether the media represents the whole disk.
  310.      * @param isWritable
  311.      * Indicates whether the media is writable.
  312.      * @param contentHint
  313.      * Hint of media's contents (optional).  See getContentHint().
  314.      * @param properties
  315.      * Substitute property table for this object (optional).
  316.      * @result
  317.      * Returns true on success, false otherwise.
  318.      */
  319.  
  320.     virtual bool init(UInt64         base,
  321.                       UInt64         size,
  322.                       UInt64         preferredBlockSize,
  323.                       bool           isEjectable,
  324.                       bool           isWhole,
  325.                       bool           isWritable,
  326.                       const char *   contentHint = 0,
  327.                       OSDictionary * properties  = 0);
  328.  
  329.     /*
  330.      * This method is called for each client interested in the services we
  331.      * provide.  The superclass links us as a parent to this client in the
  332.      * I/O Kit registry on success.
  333.      */
  334.  
  335.     bool attachToChild(IORegistryEntry * client, const IORegistryPlane *);
  336.  
  337.     /*
  338.      * This method is called for each client that loses interest in the
  339.      * services we provide.  The superclass unlinks us from this client
  340.      * in the I/O Kit registry on success.
  341.      */
  342.  
  343.     void detachFromChild(IORegistryEntry * client, const IORegistryPlane *);
  344.  
  345.     /*
  346.      * I/O Kit is in the process of searching for a candidate object that wishes
  347.      * to match against an IOLocation={x} dictionary of properties.  This is the
  348.      * method called to determine whether this object wants to be the candidate.
  349.      *
  350.      * The matchLocation method should return "this" if it decides to match with
  351.      * the IOLocation={x} dictionary, otherwise it should call the superclass to
  352.      * continue with the search and skip this object as a candidate.
  353.      *
  354.      * If this object chooses to match, the dictionary {x} will be passed to the
  355.      * standard (passive) matching method matchPropertyTable for comparison.
  356.      */
  357.  
  358.     virtual IOService * matchLocation(IOService * client);
  359.  
  360.     /*
  361.      * Compare the properties in the supplied table to this object's properties.
  362.      */
  363.  
  364.     virtual bool matchPropertyTable(OSDictionary * table, SInt32 * score);
  365.  
  366.     /*
  367.      * Obtain a path to this service object.
  368.      */
  369.  
  370.     virtual bool getPath(char * path, int * len, const IORegistryPlane *) const;
  371.  
  372.     /*!
  373.      * @function read
  374.      * @discussion
  375.      * Read data from the storage object at the specified byte offset into the
  376.      * specified buffer, asynchronously.   When the read completes, the caller
  377.      * will be notified via the specified completion action.
  378.      *
  379.      * The buffer will be retained for the duration of the read.
  380.      * @param client
  381.      * Client requesting the read.
  382.      * @param byteStart
  383.      * Starting byte offset for the data transfer.
  384.      * @param buffer
  385.      * Buffer for the data transfer.  The size of the buffer implies the size of
  386.      * the data transfer.
  387.      * @param completion
  388.      * Completion routine to call once the data transfer is complete.
  389.      */
  390.  
  391.     virtual void read(IOService *          client,
  392.                       UInt64               byteStart,
  393.                       IOMemoryDescriptor * buffer,
  394.                       IOStorageCompletion  completion);
  395.  
  396.     /*!
  397.      * @function write
  398.      * @discussion
  399.      * Write data into the storage object at the specified byte offset from the
  400.      * specified buffer, asynchronously.   When the write completes, the caller
  401.      * will be notified via the specified completion action.
  402.      *
  403.      * The buffer will be retained for the duration of the write.
  404.      * @param client
  405.      * Client requesting the write.
  406.      * @param byteStart
  407.      * Starting byte offset for the data transfer.
  408.      * @param buffer
  409.      * Buffer for the data transfer.  The size of the buffer implies the size of
  410.      * the data transfer.
  411.      * @param completion
  412.      * Completion routine to call once the data transfer is complete.
  413.      */
  414.  
  415.     virtual void write(IOService *          client,
  416.                        UInt64               byteStart,
  417.                        IOMemoryDescriptor * buffer,
  418.                        IOStorageCompletion  completion);
  419.  
  420.     /*!
  421.      * @function getPreferredBlockSize
  422.      * @discussion
  423.      * Ask the media object for its natural block size.  This information
  424.      * is useful to clients that want to optimize access to the media.
  425.      * @result
  426.      * Natural block size, in bytes.
  427.      */
  428.  
  429.     virtual UInt64 getPreferredBlockSize() const;
  430.  
  431.     /*!
  432.      * @function getSize
  433.      * @discussion
  434.      * Ask the media object for its total length in bytes.
  435.      * @result
  436.      * Media size, in bytes.
  437.      */
  438.  
  439.     virtual UInt64 getSize() const;
  440.  
  441.     /*!
  442.      * @function getBase
  443.      * @discussion
  444.      * Ask the media object for its byte offset relative to its provider media
  445.      * object below it in the storage hierarchy.
  446.      * Media offset, in bytes.
  447.      */
  448.  
  449.     virtual UInt64 getBase() const;
  450.  
  451.     /*!
  452.      * @function isEjectable
  453.      * @discussion
  454.      * Ask the media object whether it is ejectable.
  455.      * @result
  456.      * Returns true if the media is ejectable, false otherwise.
  457.      */
  458.  
  459.     virtual bool isEjectable() const;
  460.  
  461.     /*!
  462.      * @function isFormatted
  463.      * @discussion
  464.      * Ask the media object whether it is formatted.
  465.      * @result
  466.      * Returns true if the media is formatted, false otherwise.
  467.      */
  468.  
  469.     virtual bool isFormatted() const;
  470.  
  471.     /*!
  472.      * @function isWhole
  473.      * @discussion
  474.      * Ask the media object whether it represents the whole disk.
  475.      * @result
  476.      * Returns true if the media represents the whole disk, false otherwise.
  477.      */
  478.  
  479.     virtual bool isWhole() const;
  480.  
  481.     /*!
  482.      * @function isWritable
  483.      * @discussion
  484.      * Ask the media object whether it is writable.
  485.      * @result
  486.      * Returns true if the media is writable, false otherwise.
  487.      */
  488.  
  489.     virtual bool isWritable() const;
  490.  
  491.     /*!
  492.      * @function getContent
  493.      * @discussion
  494.      * Ask the media object for a description of its contents.  The description
  495.      * is the same as the hint at the time of the object's creation,  but it is
  496.      * possible that the description be overrided by a client (which has probed
  497.      * the media and identified the content correctly) of the media object.  It
  498.      * is more accurate than the hint for this reason.  The string is formed in
  499.      * the likeness of Apple's "Apple_HFS" strings.
  500.      *
  501.      * The content description can be overrided by any client that matches onto
  502.      * this media object with a match category of kIOStorageCategory.  The media
  503.      * object checks for a kIOMediaContentMask property in the client, and if it
  504.      * finds one, it copies it into kIOMediaContent property.
  505.      * @result
  506.      * Description of media's contents.
  507.      */
  508.  
  509.     virtual const char * getContent() const;
  510.  
  511.     /*!
  512.      * @function getContentHint
  513.      * @discussion
  514.      * Ask the media object for a hint of its contents.  The hint is set at the
  515.      * time of the object's creation, should the creator have a clue as to what
  516.      * it may contain.  The hint string does not change for the lifetime of the
  517.      * object and is also formed in the likeness of Apple's "Apple_HFS" strings.
  518.      * @result
  519.      * Hint of media's contents.
  520.      */
  521.  
  522.     virtual const char * getContentHint() const;
  523.  
  524.     /*
  525.      * Obtain this object's provider.  We override the superclass's method to
  526.      * return a more specific subclass of OSObject -- IOStorage.  This method
  527.      * serves simply as a convenience to subclass developers.
  528.      */
  529.  
  530.     virtual IOStorage * getProvider() const
  531.     {
  532.         return (IOStorage *) IOStorage::getProvider();
  533.     }
  534. };
  535.  
  536. #endif /* defined(KERNEL) && defined(__cplusplus) */
  537.  
  538. #endif /* !_IOMEDIA_H */
  539.